<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>Datatracker development notes</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
<style type="text/css">

/*
:Author: Henrik Levkowetz
:Contact: henrik@levkowetz.com
:Copyright: This stylesheet has been placed in the public domain.

Stylesheet for use with Docutils.  
*/

/* Your customizations go here.  For example: */

.document {
	margin: 0.2em 0.4em;
	width: 50em;
}
/* Undo some of the settings above, for fully css compliant browsers. */
/* The qualification of the elements hide this from less capable browsers. */
div[class=document] {
	width: auto;
	max-width: 50em;	/* 58em = 128ex in the design browser */
}

cite	{
	display: block;
	width: 100%;
	text-align: right;
}

</style>
</head>
<body>
<div class="document" id="datatracker-development-notes">
<h1 class="title">Datatracker development notes</h1>

<div class="section" id="introduction">
<h1>Introduction</h1>
<p>This file should be ordered with the most recent entries at the top.</p>
<p>Before March 2014, notes on choices made and paths taken, to the extent they
have been written, has been sent by email and thus don't exist as a collection
in one place.</p>
<p>With my recent investigations of code analysis tools, I thought it might be
a good idea to start collecting these in one place for the project.</p>
<blockquote style="border-left: 0">
<cite>Henrik &lt;henrik&#64;levkowetz.com&gt;, 23 Mar 2014</cite></blockquote>
</div>
<div class="section" id="code-analysis-tools">
<h1>Code Analysis Tools</h1>
<div class="section" id="pyflakes">
<h2>PyFlakes</h2>
<p>Pyflakes has proved robust and easy to work with, and has shown no false
positives in the messages provided.  It has been included in the form of a
standalone management command, as well as a test suite test.</p>
</div>
<div class="section" id="vulture">
<h2>Vulture</h2>
<p>Vulture has been a disappointment.  Given that the purpose of using it was to
discover dead code, it was necessary to extend the Vulture class to also parse
and process variables in template files, as these are points where reference
back to object methods and object attributes can be made.</p>
<p>Unfortunately, once this extension was in place, it turned out that the amount
of remaining false positives was unreasonably large, because Vulture fails to
understand that the declarative style of Django models (from
django.models.Model) and admin classes (from django.contrib.admin.ModelAdmin)
doesn't in fact constitute unused class attributes.</p>
<p>Finally, it turns out that Vulture is really simpleminded about what
constitutes usage.  It has one set of global lists for used functions, used
attributes, and used variables; any instance of overlapping function, method,
variable, or attribute naming across modules will result in one instance of
use in one module masking lack of usage in all other modules.</p>
<p>At the moment, it looks like it might be a better way forward to see if
PyFlakes could be extended with some dead code capability, than to continue to
pound on what seems to be a broken framework in Vulture.</p>
</div>
<div class="section" id="pylint">
<h2>PyLint</h2>
<p>PyLint has been excluded from futher consideration because it doesn't only
parse the code, it also executes it, which comes with both a speed penalty and
the possibility of triggering unwanted side effects of doing an analysis run.</p>
</div>
<div class="section" id="pychecker">
<h2>PyChecker</h2>
<p>PyChecker turned out to require much more fiddling than PyFlakes in order to
do the right thing, but once it was made to run on the datatracker code, and
ignore the django code, it didn't report anything that PyFlakes hadn't already
caught.</p>
<blockquote style="border-left: 0">
    <cite>Henrik &lt;henrik&#64;levkowetz.com&gt;, 23 Mar 2014</cite>
</blockquote>
</div>
</div>
</div>
</body>
</html>
